home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / texts / hsc.lha / hsc / src_docs / features / spctags.hsc < prev    next >
Text File  |  1996-05-15  |  7KB  |  204 lines
  1. <WEBPAGE chapter="hsc - Features - " title="Special Tags"
  2.     PREV=":distrib.html"
  3.     NEXT="syntax.html">
  4.  
  5. <P><B>hsc</B> adds some special tags, which can be quite useful for maintainers
  6. of big HTML-projects.</P>
  7.  
  8. <UL>
  9. <LI><A HREF="#comments"><TG>* <I>comment</I> *</TG></A> insert comments
  10. <LI><A HREF="#exec"><TG>$exec</TG></A> execute shell commands during conversion
  11. <LI><A HREF="if.html"><TG>$if</TG> <TG>$else</TG></A> conditional conversion
  12. <LI><A HREF="#include"><TG>$include</TG></A> include a file
  13. <LI><A HREF="#insert"><TG>$insert</TG></A> insert several stuff
  14. <LI><A HREF="#define"><TG>$define</TG></A> define a new (global) attribute
  15. <LI><A HREF="#let"><TG>$let</TG></A> set new attribute value
  16. <LI><A HREF=":macro/macros.html"><TG>$macro</TG></A> define macro-tags
  17. <LI><A HREF="#message"><TG>$message</TG></A> display user message
  18. <LI><A HREF="#expression"><TG>( <I>expression</I> )</TG></A> insert expression
  19. <LI><A HREF="#dontparse"><TG>|  <I>don't parse</I> |</TG></A> don't parse section
  20. </UL>
  21.  
  22. <$macro SPCTAG NAME:string/r TITLE:string/r>
  23. <HR>
  24. <A NAME=(name)><H2><$INSERT TEXT=(title)></H2></A>
  25. </$macro>
  26.  
  27. <SPCTAG NAME="comments" TITLE="Comments">
  28.     You can insert a comment with
  29.  
  30.     <BLOCKQUOTE>
  31.     <TG>* This is a hsc-comment *</TG>
  32.     </BLOCKQUOTE>
  33.  
  34.     You can also nest such comments.<P>
  35.  
  36.     And you can comment out sections of html-source without any problems
  37.     for the browser. This simply is possible because comments in the
  38.     HSC-source are not written to the HTML-object.<P>
  39.  
  40.     Of course, if you need the standard comments, you can use
  41.     <BLOCKQUOTE>
  42.     <TG>!-- This is a html/sgml-comment --</TG>
  43.     </BLOCKQUOTE>
  44.     as usual.<P>
  45.  
  46. <SPCTAG NAME="exec" TITLE="Execute shell command">
  47.  
  48.     A shell command can be executed with
  49.     <$source PRE>
  50.     <$exec COMMAND="command">
  51.     </$source>
  52.  
  53.     An example usage would be to insert a listing of a
  54.     directory:
  55.  
  56. <$include FILE="exmpl/exec.hsc" SOURCE PRE>
  57.  
  58.     And the data created by this code sequence would look
  59.     like this:
  60.  
  61.     <$include FILE="exmpl/exec.hsc">
  62.  
  63.     If the command's return code is not equal to zero, a
  64.     warning message will be displayed.
  65.  
  66. <SPCTAG NAME="if" TITLE="Conditional conversion">
  67.     As there is a lot to tell about this feature, it has it's <A HREF="if.html">
  68.     own page</A>.
  69.  
  70. <SPCTAG NAME="include" TITLE="Include file">
  71.     A <hsc>-file can be included to the text using
  72.  
  73.     <BLOCKQUOTE>
  74.     <TG>$include FILE="filename" [SOURCE] [PRE]</TG>
  75.     </BLOCKQUOTE>
  76.  
  77.     If you include a file this way, it is handled as an usual
  78.     <hsc>-file. That means, all tags and special characters are
  79.     handled as before.<P>
  80.  
  81.     To include a source file, eg a C- or HTML-source so that the
  82.     tags are not interpreted but displayed, add the optional
  83.     boolean attribute <CODE>SOURCE</CODE>.
  84.  
  85.     <BLOCKQUOTE>
  86.     <TG>$include FILE="hugo.c" SOURCE</TG>
  87.     </BLOCKQUOTE>
  88.  
  89.     Now the basic special characters "<", ">" and "&" are
  90.     replaced by their entities.<P>
  91.     Note that this does <STRONG>not</STRONG> include a <TG>PRE</TG>-tag
  92.     to render the text as it exists with the same line breaks and
  93.     spaces.<P>
  94.  
  95.     To get this done, you should use the optional boolean attribute
  96.     <CODE>PRE</CODE>. This inserts a <TG>PRE</TG> before the included
  97.     data and a <TG>/PRE</TG> afterwards.
  98.  
  99.  
  100. <SPCTAG NAME="insert" TITLE="Insert several stuff">
  101.     You can insert several stuff using the tag
  102.  
  103.     <BLOCKQUOTE>
  104.     <TG>$insert what [options]</TG>
  105.     </BLOCKQUOTE>
  106.  
  107.     <H3>Insert current date and time</H3>
  108.         You can insert the current date and time simply by
  109.           <UBQ><TG>$insert TIME</TG></UBQ>
  110.         using a default format.<P>
  111.  
  112.         Optionally, you can pass a format-string, that discribes the time.
  113.         As <hsc> just calls the ANSI-C function
  114.         <A HREF="strftime.txt"><CODE>strftime()</CODE></A>
  115.         to perform that task, you can use the same format specifications.
  116.  
  117.         Example:<BR>
  118.           <UBQ><TG>$insert TIME FORMAT="%b %d  %y"</TG></UBQ>
  119.         inserts current date with the strange ANSI-C
  120.         <CODE>__TIME__</CODE>-format.
  121.  
  122.     <H3>Insert text</H3>
  123.         As an required argument, you must give a string
  124.         that contains the text. Example:
  125.         <UBQ><TG>$insert TEXT="hugo was here!"</TG></UBQ>
  126.         inserts the text "<CODE>hugo was here</CODE>". Of course, this does not
  127.         make much sense.<TG>$insert TEXT="..."</TG> is suggested to be used
  128.         with attribute values. Example:
  129.         <UBQ><TG>$insert TEXT=<href></TG></UBQ>
  130.         inserts the value of the macro-attribute <CODE>href</CODE>.
  131.  
  132. <SPCTAG NAME="define" TITLE="Define attributes">
  133.  
  134.     You can create an attribute and pass a value to it via
  135.  
  136.     <BLOCKQUOTE>
  137.     <TG>$define <I><A HREF=":macro/attrib.html">attribute</A></I></TG>
  138.     </BLOCKQUOTE>
  139.  
  140.     <P>If you define an attribute via <TG>$define</TG> inside a macro, it is of
  141.     local existence only and is removed after processing the macro. You
  142.     can suppress this with using the attribute flag <CODE>/GLOBAL</CODE>: in
  143.     this case, the attribute exists until the end of conversion.</P>
  144.  
  145.     <P>You can use the flag <CODE>/CONST</CODE> to make the attribute read-only.
  146.     That means it can't be overwritten by <TG>$let</TG></P>
  147.  
  148. <SPCTAG NAME="let" TITLE="Set new attribute value">
  149.  
  150.     You can update an attribute's value with
  151.  
  152.     <BLOCKQUOTE>
  153.     <TG>$let <I><A HREF=":macro/attrib.html">attribute_name</A></I> =
  154.     <I>new_value</I></TG>
  155.     </BLOCKQUOTE>
  156.  
  157.     Example:<BR>
  158.     <$source PRE>
  159.     <$define hugo:string="hugo">       <* create hugo and set to "hugo" *>
  160.     <$let hugo=(hugo+" ist doof.")>    <* update it to "hugo ist doof." *>
  161.     </$source>
  162.  
  163. <SPCTAG NAME="macro" TITLE="Define macros">
  164.     I think, this feature needs an <A HREF=":macro/macros.html">
  165.     own page</A>...
  166.  
  167. <SPCTAG NAME="message" TITLE="User messages">
  168.     During conversion, you can invoke messages by yourself using
  169.     <$source PRE>
  170.     <$message TEXT="message text" [CLASS="class"]>
  171.     </$source>
  172.     For an example, look at <A HREF="#exec"><TG>$exec</TG></A>.
  173.  
  174. <SPCTAG NAME="expression" TITLE="Insert expression">
  175.  
  176.     This tag is used to insert data of attributes an
  177.     <A HREF="expressions.html">expressions</A>. For example:
  178.  
  179.     <$source PRE>
  180.     <$define hugo:string="hugo">       <* create hugo and set to "hugo" *>
  181.     <(hugo+" ist doof.")>              <* insert text "hugo ist doof." *>
  182.     </$source>
  183.  
  184. <SPCTAG NAME="dontparse" TITLE="Don't parse section">
  185.  
  186.     If you created some perverted HTML source or use features
  187.     <hsc> can't handle (which is theoretically impossible), you
  188.     can keep of <hsc> from parsing this section by surrounding it with
  189.     <TG>| ... |</TG>. Of course, this is a dirty hide-out and should
  190.     be used only for special cases.
  191.  
  192. <SPCTAG NAME="defent" TITLE="Define a new entity">
  193.  
  194. This tag should be used within <FILE>hsc.prefs</FILE> only. It defines
  195. a new entity.
  196.  
  197. <SPCTAG NAME="deftag" TITLE="Define a new tag">
  198.  
  199. This tag should be used within <FILE>hsc.prefs</FILE> only. It defines
  200. a new tag, and is used quite similar to <ln_macro>.
  201.  
  202. <BR>
  203. </WEBPAGE>
  204.